Metadata

In order to define Insight Definition triggering or audience conditions the User Interface needs a bit more information on each Custom event property. This information defines for instance which properties are available for comparison, how to display them and what comparisons should be allowed. This information will be further referred to as Metadata.

note

Following examples assume that a custom event CarbonInsightCreated has been created. See Events configuration on how to register a custom event.

Update event Metadata

Event metadata like name and description can be modified through a following request:

PUT /integration/insights/v1/events/metadata/{eventTypeIdentifier}

curl -X 'PUT' '/integration/insights/v1/events/metadata/CarbonInsightCreated' \
  -H 'accept: text/plain' \
  -H 'Authorization: Bearer {token}' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "Carbon Insight",
  "description": "Event triggered each time a new Carbon Insight is generated"
}'

200 OK

{
  "data": {
    "eventTypeIdentifier": "CarbonInsightCreated",
    "name": "Carbon Insight",
    "description": "Event triggered each time a new Carbon Insight is generated",
    "isAvailable": true,
    "fields": {
      "UserIdentifier": {
        "label": "UserIdentifier",
        "type": "text",
        "tooltip": null,
        "disabled": true
      },
      ...
    }
  }
}

Property	Is Required	Description
name	No	Human friendly event name to be displayed in Triggering events selection. If value is missing then event name will not be updated.
description	No	Extended event description which should elaborate on the event purpose. It might be displayed in Triggering events selection as a tooltip. If value is missing then event description will not be updated.

Update field Metadata

In order to update a selected field of an event please run a following request

PUT /integration/insights/v1/events/metadata/{eventTypeIdentifier}

  curl --request PUT '/integration/insights/v1/events/metadata/CarbonInsightCreated' \
    -H 'accept: text/plain' \
    -H 'Authorization: Bearer {token}' \
    -H 'Content-Type: application/json' \
    -d '{
      "fields": {
          "AccountIdentifier": {
              "label": "Account identifier",
              "tooltip": "Identifier of the account",
              "disabled": false
          },
          "CarbonGrams": {
              "disabled": false,
              "label": "Carbon footprint (g)",
              "tooltip": "Carbon footprint in grams associated with the transaction",
            }
      }
  }'

200 OK

{
  "data": {
    "eventTypeIdentifier": "CarbonInsightCreated",
    "name": "Carbon Insight",
    "description": "Event triggered each time a new Carbon Insight is generated",
    "isAvailable": true,
    "fields": {
      "UserIdentifier": {
        "label": "UserIdentifier",
        "type": "text",
        "tooltip": null,
        "disabled": true
      },
      ...
      "AccountIdentifier": {
        "label": "Account identifier",
        "type": "text",
        "tooltip": "Identifier of the account",
        "disabled": false
      },
      "TransactionDateTime": {
        "label": "TransactionDateTime",
        "type": "datetime",
        "tooltip": null,
        "disabled": true
      },
      "CarbonGrams": {
        "label": "Carbon footprint (g)",
        "type": "number",
        "tooltip": "Carbon footprint in grams associated with the transaction",
        "disabled": false
      },
      ...
    }
  }
}

Property	Is Required	Description
fields	No	Collection of field metadata to update, indexed by field names
.label	No	Human friendly field label. It can contain whitespace characters. If value is missing then field label will not be updated.
.tooltip	No	Extended field description which should elaborate on the field purpose. It might be displayed in a tooltip. If value is missing then field tooltip will not be updated.
.disabled	No	Disabled fields are not available when defining Insight Definition triggering or audience conditions

Error responses

This section describes example error responses when updating Event metadata.

Updating not existing property

PUT /integration/insights/v1/events/metadata/{eventTypeIdentifier}

curl --request PUT '/integration/insights/v1/events/metadata/CarbonInsightCreated' \
  -H 'accept: text/plain' \
  -H 'Authorization: Bearer {token}' \
  -H 'Content-Type: application/json' \
  -d '{
  "fields": {
      "Account": {
          "name": "Account identifier",
          "description": "Identifier of the account",
          "disabled": false
          }
    }
}'

400 Bad request

{
  "errors": [
    {
      "message": "Bad Request",
      "messageDetails": "Some used fields in Fields Account can not be updated, because they do not exist for the event ID:CarbonInsightCreated",
      "modelState": null
    }
  ]
}

Update complex property Metadata

In order to update a selected complex field of an event please run a following request.

PUT /integration/insights/v1/events/metadata/{eventTypeIdentifier}

  curl --request PUT '/integration/insights/v1/events/metadata/CarbonInsightCreated' \
    -H 'accept: text/plain' \
    -H 'Authorization: Bearer {token}' \
    -H 'Content-Type: application/json' \
    -d '{
  "fields": {
    "SourceAccount": {
      "disabled": false,
      "fields": {
        "AccountIdentifier": {
          "disabled": false,
          "label": "Source Account Identifier",
          "tooltip": "Source account identifier"
        },
        "AccountType": {
          "disabled": false,
          "label": "Source account type",
          "tooltip": "Source account type description"
        }
      }
    }
  }
}'

200 OK

{
  "data": {
    "eventTypeIdentifier": "CarbonInsightCreated",
    "name": "Carbon Insight",
    "description": "Event triggered each time a new Carbon Insight is generated",
    "isAvailable": true,
    "fields": {
      ...
      "SourceAccount": {
        "label": "SourceAccount",
        "type": "!struct",
        "subfields": {
          "AccountIdentifier": {
            "label": "Source Account Identifier",
            "type": "text",
            "tooltip": "Source account identifier",
            "disabled": false
          },
          "AccountType": {
            "label": "Source account type",
            "type": "number",
            "tooltip": "Source account type description",
            "disabled": false
          }
        }
      }
    }
  }
}

Property	Is Required	Description
fields	No	Collection of field metadata to update, indexed by field names
.fields	No	Collection of complex field fields, indexed by field name. This is a recursive data structure.

Custom types

Sometimes when defining Insight Definitions triggering or audience conditions we would like to have a more fine grain controller over how to compare values. For instance when defining a rule for a Currency: text field we don't want to allow users to define rules comparing a Currency: text field to any text value. Ideally we would like to restrict our users to specify only valid currency values like EUR, USD or any other ISO Currency code. This is when Custom Types come into play.

Custom types feature allows admin to define a type which will limit the possible comparison values to either a static list of available values or a dynamic list returned from an external API. Custom Type can either have a 'string' or a 'numeric' idType. This determines event properties that the Custom Type could be assigned to (numeric Custom types could only be assigned to numeric properties etc.).

Custom type needs to be created first before it can be assigned to a field.

POST /integration/insights/v1/metadata/custom-types

  curl --request POST '/integration/insights/v1/metadata/custom-types' \
  -H 'accept: text/plain' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "AccountType",
  "prompt": "Select Account type",
  "valueDomain": {
    "fetchUrl": null,
    "predefinedValues": {
      "CUR": "Current",
      "SVG": "Savings"
    },
    "idValueType": "String"
  }
}'

201 Created

{
  "data": {
    "name": "AccountType",
    "prompt": "Select Account type",
    "isDisabled": false,
    "domain": {
      "idType": "String",
      "fetchUrl": null,
      "predefinedValues": {
        "CUR": "Current",
        "SVG": "Savings"
      }
    }
  }
}

Property	Is Required	Description
name	Yes	Custom type name. Needs to be a globally unique name
prompt	No	Prompt text to be displayed in the value selection widget during Insight Definition triggering or audience conditions definition
valueDomain	Yes	Configuration describing how to populate drop-down list
valueDomain.FetchUrl	No *	Url to the controller action that returns a list of items. The response must be a JSON array of objects that have id and name properties. Mutually exclusive with PredefinedValues property.
valueDomain.predefinedValues	No *	A collection of key-value pairs of items that the user can select from. Mutually exclusive with FetchUrl property.
valueDomain.idValueType	Yes	Type the ids of items in the domain. Possible values Numeric

Once created Custom type can be updated through a following request:

PUT /integration/insights/v1/metadata/custom-types/{customTypeName}

  curl --request PUT '/integration/insights/v1/metadata/custom-types/AccountType' \
  -H 'accept: text/plain' \
  -H 'Content-Type: application/json' \
  -d '{
  "prompt": "Select Account type",
  "valueDomain": {
    "fetchUrl": null,
    "predefinedValues": {
      "CUR": "Current",
      "SVG": "Savings"
    }
  }
}'

200 OK

{
  "data": {
    "name": "AccountType",
    "prompt": "Select Account type",
    "isDisabled": false,
    "domain": {
      "idType": "String",
      "fetchUrl": null,
      "predefinedValues": {
        "CUR": "Current",
        "SVG": "Savings"
      }
    }
  }
}

Custom type details can be fetched using following request:

GET /integration/insights/v1/metadata/custom-types/{customTypeName}

  curl --request GET '/integration/insights/v1/metadata/custom-types/AccountType' \
  -H 'accept: text/plain'

200 OK

{
  "data": {
    "name": "AccountType",
    "prompt": "Select Account type",
    "isDisabled": false,
    "domain": {
      "idType": "String",
      "fetchUrl": null,
      "predefinedValues": {
        "CUR": "Current",
        "SVG": "Savings"
      }
    }
  }
}

Using custom types

Custom type can be assigned to a field using a following request:

PUT /integration/insights/v1/events/metadata/{id}

  curl --request PUT '/integration/insights/v1/events/metadata/{id}' \
    -H 'accept: text/plain' \
    -H 'Authorization: Bearer {token}' \
    -H 'Content-Type: application/json' \
    -d '{
      "fields": {
          "Currency": {
              "type": "CurrencyCode"
          },
          "SourceAccount": {
            "fields": {
                "AccountType" : {
                    "type": "AccountType"
                }
            }
          }
      }
  }'

200 OK

{
  "data": {
    "eventTypeIdentifier": "CarbonInsightCreated",
    "name": "Carbon Insight",
    "description": "Event triggered each time a new Carbon Insight is generated",
    "isAvailable": true,
    "fields": {
      ...
      "Currency": {
        "label": "Currency",
        "type": "CurrencyCode",
        "tooltip": null,
        "disabled": true
      },
      "SourceAccount": {
        "label": "SourceAccount",
        "type": "!struct",
        "subfields": {
          "AccountIdentifier": {
            "label": "Source Account Identifier",
            "type": "text",
            "tooltip": "Source account identifier",
            "disabled": false
          },
          "AccountType": {
            "label": "Source account type",
            "type": "AccountType",
            "tooltip": "Source account type description",
            "disabled": false
          }
        }
      }
    }
  }
}

Property	Is Required	Description
fields	No	Collection of field metadata to update, indexed by field names
.type	No	Custom type name to be assigned to the field. Custom Type needs to exist first. Custom type Identifier type must match the underlying field type. Can't assign a numerical custom type to a text field.

Error responses

Trying to set AccountIdentifier type to a non Custom Type: number

PUT /integration/insights/v1/events/metadata/{eventTypeIdentifier}

curl --request PUT '/integration/insights/v1/events/metadata/CarbonInsightCreated' \
    -H 'accept: text/plain' \
    -H 'Authorization: Bearer {token}' \
    -H 'Content-Type: application/json' \
    -d ' {
      "fields": {
        "AccountIdentifier": {
            "name": "Account identifier",
            "description": "Identifier of the account",
            "disabled": false,
            "type": "number"
          }
      }
  }'

400 Bad requets

{
  "errors": [
    {
      "message": "Bad Request",
      "messageDetails": "[AccountIdentifier] Trying to assign type [number] which isn't an available Custom Type,A custom type for [AccountIdentifier:text] field must have a 'String' identifier type",
      "modelState": null
    }
  ]
}

Trying to assign a string Custom Type to a numeric field

note

It is assumed that numeric Custom Type AccountType exists in the system.

PUT /integration/insights/v1/events/metadata/{id}

    curl --request PUT '/integration/insights/v1/events/metadata/{id}' \
      -H 'accept: text/plain' \
      -H 'Authorization: Bearer {token}' \
      -H 'Content-Type: application/json' \
      -d '{
     "fields": {
        "AccountIdentifier": {
           "name": "Account identifier",
           "description": "Identifier of the account",
           "disabled": false,
           "type": "AccountType"
         }
     }
  }'

400 Bad request

{
  "errors": [
    {
      "message": "Bad Request",
      "messageDetails": "A custom type for [AccountIdentifier:text] field must have a 'String' identifier type",
      "modelState": null
    }
  ]
}